<!doctype html>

<html>
<head>
  <link rel="shortcut icon" href="static/images/favicon.ico" type="image/x-icon">
  <title>mockclock.js (Closure Library API Documentation - JavaScript)</title>
  <link rel="stylesheet" href="static/css/base.css">
  <link rel="stylesheet" href="static/css/doc.css">
  <link rel="stylesheet" href="static/css/sidetree.css">
  <link rel="stylesheet" href="static/css/prettify.css">

  <script>
     var _staticFilePath = "static/";
  </script>

  <script src="static/js/doc.js">
  </script>

  <meta charset="utf8">
</head>

<body onload="prettyPrint()">

<div id="header">
  <div class="g-section g-tpl-50-50 g-split">
    <div class="g-unit g-first">
      <a id="logo" href="index.html">Closure Library API Documentation</a>
    </div>

    <div class="g-unit">
      <div class="g-c">
        <strong>Go to class or file:</strong>
        <input type="text" id="ac">
      </div>
    </div>
  </div>
</div>

<div class="clear"></div>

<h2><a href="closure_goog_testing_mockclock.js.html">mockclock.js</a></h2>

<pre class="prettyprint lang-js">
<a name="line1"></a>// Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
<a name="line2"></a>// you may not use this file except in compliance with the License.
<a name="line3"></a>// You may obtain a copy of the License at
<a name="line4"></a>//
<a name="line5"></a>//     http://www.apache.org/licenses/LICENSE-2.0
<a name="line6"></a>//
<a name="line7"></a>// Unless required by applicable law or agreed to in writing, software
<a name="line8"></a>// distributed under the License is distributed on an &quot;AS IS&quot; BASIS,
<a name="line9"></a>// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
<a name="line10"></a>// See the License for the specific language governing permissions and
<a name="line11"></a>// limitations under the License.
<a name="line12"></a>
<a name="line13"></a>// Copyright 2007 Google Inc. All Rights Reserved.
<a name="line14"></a>
<a name="line15"></a>/**
<a name="line16"></a> * @fileoverview Mock Clock implementation for working with setTimeout,
<a name="line17"></a> * setInterval, clearTimeout and clearInterval within unit tests.
<a name="line18"></a> *
<a name="line19"></a> * Derrived from jsUnitMockTimeout.js, contributed to JsUnit by
<a name="line20"></a> * Pivotal Computer Systems, www.pivotalsf.com
<a name="line21"></a> *
<a name="line22"></a> */
<a name="line23"></a>
<a name="line24"></a>goog.provide(&#39;goog.testing.MockClock&#39;);
<a name="line25"></a>
<a name="line26"></a>goog.require(&#39;goog.Disposable&#39;);
<a name="line27"></a>
<a name="line28"></a>
<a name="line29"></a>/**
<a name="line30"></a> * Class for unit testing code that uses setTimeout and clearTimeout.
<a name="line31"></a> * @param {boolean} opt_autoInstall Install the MockClock at constuction time.
<a name="line32"></a> * @constructor
<a name="line33"></a> * @extends {goog.Disposable}
<a name="line34"></a> */
<a name="line35"></a>goog.testing.MockClock = function(opt_autoInstall) {
<a name="line36"></a>  goog.Disposable.call(this);
<a name="line37"></a>
<a name="line38"></a>  /**
<a name="line39"></a>   * Reverse-order queue of timers to fire.
<a name="line40"></a>   *
<a name="line41"></a>   * The last item of the queue is popped off.  Insertion happens from the
<a name="line42"></a>   * right.  For example, the expiration times for each element of the queue
<a name="line43"></a>   * might be in the order 300, 200, 200.
<a name="line44"></a>   *
<a name="line45"></a>   * @type {Array.&lt;Object&gt;}
<a name="line46"></a>   * @private
<a name="line47"></a>   */
<a name="line48"></a>  this.queue_ = [];
<a name="line49"></a>
<a name="line50"></a>  /**
<a name="line51"></a>   * Set of timeouts that should be treated as cancelled.
<a name="line52"></a>   *
<a name="line53"></a>   * Rather than removing cancelled timers directly from the queue, this set
<a name="line54"></a>   * simply marks them as deleted so that they can be ignored when their
<a name="line55"></a>   * turn comes up.  The keys are the timeout keys that are cancelled, each
<a name="line56"></a>   * mapping to true.
<a name="line57"></a>   *
<a name="line58"></a>   * @type {Object}
<a name="line59"></a>   * @private
<a name="line60"></a>   */
<a name="line61"></a>  this.deletedKeys_ = {};
<a name="line62"></a>
<a name="line63"></a>  if (opt_autoInstall) {
<a name="line64"></a>    this.install();
<a name="line65"></a>  }
<a name="line66"></a>};
<a name="line67"></a>goog.inherits(goog.testing.MockClock, goog.Disposable);
<a name="line68"></a>
<a name="line69"></a>
<a name="line70"></a>/**
<a name="line71"></a> * Count of the number of timeouts made.
<a name="line72"></a> * @type {number}
<a name="line73"></a> * @private
<a name="line74"></a> */
<a name="line75"></a>goog.testing.MockClock.prototype.timeoutsMade_ = 0;
<a name="line76"></a>
<a name="line77"></a>
<a name="line78"></a>/**
<a name="line79"></a> * Whether mock clock is installed.
<a name="line80"></a> * @type {boolean}
<a name="line81"></a> * @private
<a name="line82"></a> */
<a name="line83"></a>goog.testing.MockClock.prototype.installed_ = false;
<a name="line84"></a>
<a name="line85"></a>
<a name="line86"></a>/**
<a name="line87"></a> * Map of deleted keys.  These keys represents keys that were deleted in a
<a name="line88"></a> * clearInterval, timeoutid -&gt; object.
<a name="line89"></a> * @type {Object?}
<a name="line90"></a> * @private
<a name="line91"></a> */
<a name="line92"></a>goog.testing.MockClock.prototype.deletedKeys_ = null;
<a name="line93"></a>
<a name="line94"></a>
<a name="line95"></a>/**
<a name="line96"></a> * The current simulated time in milliseconds.
<a name="line97"></a> * @type {number}
<a name="line98"></a> * @private
<a name="line99"></a> */
<a name="line100"></a>goog.testing.MockClock.prototype.nowMillis_ = 0;
<a name="line101"></a>
<a name="line102"></a>
<a name="line103"></a>/**
<a name="line104"></a> * Additional delay between the time a timeout was set to fire, and the time
<a name="line105"></a> * it actually fires.  Useful for testing workarounds for this Firefox 2 bug:
<a name="line106"></a> * https://bugzilla.mozilla.org/show_bug.cgi?id=291386
<a name="line107"></a> * May be negative.
<a name="line108"></a> * @type {number}
<a name="line109"></a> * @private
<a name="line110"></a> */
<a name="line111"></a>goog.testing.MockClock.prototype.timeoutDelay_ = 0;
<a name="line112"></a>
<a name="line113"></a>
<a name="line114"></a>/**
<a name="line115"></a> * Reference to the original implementation of setTimeout.
<a name="line116"></a> * @type {function(this:Window, (Function|string), number, *=): number}
<a name="line117"></a> * @private
<a name="line118"></a> */
<a name="line119"></a>goog.testing.MockClock.prototype.oldSetTimeout_ = window.setTimeout;
<a name="line120"></a>
<a name="line121"></a>
<a name="line122"></a>/**
<a name="line123"></a> * Reference to the original implementation of setInterval.
<a name="line124"></a> * @type {function(this:Window, (Function|string), number, *=): number}
<a name="line125"></a> * @private
<a name="line126"></a> */
<a name="line127"></a>goog.testing.MockClock.prototype.oldSetInterval_ = window.setInterval;
<a name="line128"></a>
<a name="line129"></a>
<a name="line130"></a>/**
<a name="line131"></a> * Reference to the original implementation of clearTimeout.
<a name="line132"></a> * @type {function(this:Window, number?=)}
<a name="line133"></a> * @private
<a name="line134"></a> */
<a name="line135"></a>goog.testing.MockClock.prototype.oldClearTimeout_ = window.clearTimeout;
<a name="line136"></a>
<a name="line137"></a>
<a name="line138"></a>/**
<a name="line139"></a> * Reference to the original implementation of clearInterval.
<a name="line140"></a> * @type {function(this:Window, number?=)}
<a name="line141"></a> * @private
<a name="line142"></a> */
<a name="line143"></a>goog.testing.MockClock.prototype.oldClearInterval_ = window.clearInterval;
<a name="line144"></a>
<a name="line145"></a>
<a name="line146"></a>/**
<a name="line147"></a> * Installs the MockClock by overriding the window object&#39;s implementation of
<a name="line148"></a> * setTimeout, setInterval, clearTimeout and clearInterval.
<a name="line149"></a> */
<a name="line150"></a>goog.testing.MockClock.prototype.install = function() {
<a name="line151"></a>  if (!this.installed_) {
<a name="line152"></a>    this.installed_ = true;
<a name="line153"></a>    window.setTimeout = goog.bind(this.setTimeout_, this);
<a name="line154"></a>    window.setInterval = goog.bind(this.setInterval_, this);
<a name="line155"></a>    window.clearTimeout = goog.bind(this.clearTimeout_, this);
<a name="line156"></a>    window.clearInterval = goog.bind(this.clearInterval_, this);
<a name="line157"></a>
<a name="line158"></a>    // Mock out goog.now
<a name="line159"></a>    this.oldGoogNow_ = goog.now;
<a name="line160"></a>    goog.now = goog.bind(this.getCurrentTime, this);
<a name="line161"></a>  }
<a name="line162"></a>};
<a name="line163"></a>
<a name="line164"></a>
<a name="line165"></a>/**
<a name="line166"></a> * Removes the MockClock&#39;s hocks into the window functions and revert to their
<a name="line167"></a> * original values.
<a name="line168"></a> */
<a name="line169"></a>goog.testing.MockClock.prototype.uninstall = function() {
<a name="line170"></a>  if (this.installed_) {
<a name="line171"></a>    this.installed_ = false;
<a name="line172"></a>    window.setTimeout = this.oldSetTimeout_;
<a name="line173"></a>    window.setInterval = this.oldSetInterval_;
<a name="line174"></a>    window.clearTimeout = this.oldClearTimeout_;
<a name="line175"></a>    window.clearInterval = this.oldClearInterval_;
<a name="line176"></a>
<a name="line177"></a>    goog.now = this.oldGoogNow_;
<a name="line178"></a>  }
<a name="line179"></a>};
<a name="line180"></a>
<a name="line181"></a>
<a name="line182"></a>/**
<a name="line183"></a> * Disposes of the MockClock.
<a name="line184"></a> */
<a name="line185"></a>goog.testing.MockClock.prototype.disposeInternal = function() {
<a name="line186"></a>  this.uninstall();
<a name="line187"></a>  delete this.oldSetTimeout_;
<a name="line188"></a>  delete this.oldSetInterval_;
<a name="line189"></a>  delete this.oldClearTimeout_;
<a name="line190"></a>  delete this.oldClearInterval_;
<a name="line191"></a>  this.queue_ = null;
<a name="line192"></a>  this.deletedKeys_ = null;
<a name="line193"></a>  goog.testing.MockClock.superClass_.disposeInternal.call(this);
<a name="line194"></a>};
<a name="line195"></a>
<a name="line196"></a>
<a name="line197"></a>/**
<a name="line198"></a> * Resets the MockClock, removing all timeouts that are scheduled and resets
<a name="line199"></a> * the fake timer count.
<a name="line200"></a> */
<a name="line201"></a>goog.testing.MockClock.prototype.reset = function() {
<a name="line202"></a>  this.queue_ = [];
<a name="line203"></a>  this.deletedKeys_ = {};
<a name="line204"></a>  this.nowMillis_ = 0;
<a name="line205"></a>  this.timeoutsMade_ = 0;
<a name="line206"></a>  this.timeoutDelay_ = 0;
<a name="line207"></a>};
<a name="line208"></a>
<a name="line209"></a>
<a name="line210"></a>/**
<a name="line211"></a> * Sets the amount of time between when a timeout is scheduled to fire and when
<a name="line212"></a> * it actually fires.
<a name="line213"></a> * @param {number} delay The delay in millseconds.  May be negative.
<a name="line214"></a> */
<a name="line215"></a>goog.testing.MockClock.prototype.setTimeoutDelay = function(delay) {
<a name="line216"></a>  this.timeoutDelay_ = delay;
<a name="line217"></a>};
<a name="line218"></a>
<a name="line219"></a>
<a name="line220"></a>/**
<a name="line221"></a> * @return {number} delay The amount of time between when a timeout is
<a name="line222"></a> *     scheduled to fire and when it actually fires, in millseconds.  May
<a name="line223"></a> *     be negative.
<a name="line224"></a> */
<a name="line225"></a>goog.testing.MockClock.prototype.getTimeoutDelay = function() {
<a name="line226"></a>  return this.timeoutDelay_;
<a name="line227"></a>};
<a name="line228"></a>
<a name="line229"></a>
<a name="line230"></a>/**
<a name="line231"></a> * Increments the MockClock&#39;s time by a given number of milliseconds, running
<a name="line232"></a> * any functions that are now overdue.
<a name="line233"></a> * @param {number} opt_millis Number of milliseconds to increment the counter.
<a name="line234"></a> *     If not specified, clock ticks 1 millisecond.
<a name="line235"></a> * @return {number} Current mock time in millis.
<a name="line236"></a> */
<a name="line237"></a>goog.testing.MockClock.prototype.tick = function(opt_millis) {
<a name="line238"></a>  if (typeof opt_millis != &#39;number&#39;) {
<a name="line239"></a>    opt_millis = 1;
<a name="line240"></a>  }
<a name="line241"></a>  var endTime = this.nowMillis_ + opt_millis;
<a name="line242"></a>  this.runFunctionsWithinRange_(endTime);
<a name="line243"></a>  this.nowMillis_ = endTime;
<a name="line244"></a>  return endTime;
<a name="line245"></a>};
<a name="line246"></a>
<a name="line247"></a>
<a name="line248"></a>/**
<a name="line249"></a> * @return {number} The number of timeouts that have been scheduled.
<a name="line250"></a> */
<a name="line251"></a>goog.testing.MockClock.prototype.getTimeoutsMade = function() {
<a name="line252"></a>  return this.timeoutsMade_;
<a name="line253"></a>};
<a name="line254"></a>
<a name="line255"></a>
<a name="line256"></a>/**
<a name="line257"></a> * @return {number} The MockClock&#39;s current time in milliseconds.
<a name="line258"></a> */
<a name="line259"></a>goog.testing.MockClock.prototype.getCurrentTime = function() {
<a name="line260"></a>  return this.nowMillis_;
<a name="line261"></a>};
<a name="line262"></a>
<a name="line263"></a>
<a name="line264"></a>/**
<a name="line265"></a> * @param {number} timeoutKey The timeout key.
<a name="line266"></a> * @return {boolean} Whether the timer has been set and not cleared,
<a name="line267"></a> *     independent of the timeout&#39;s expiration.  In other words, the timeout
<a name="line268"></a> *     could have passed or could be scheduled for the future.  Either way,
<a name="line269"></a> *     this function returns true or false depending only on whether the
<a name="line270"></a> *     provided timeoutKey represents a timeout that has been set and not
<a name="line271"></a> *     cleared.
<a name="line272"></a> */
<a name="line273"></a>goog.testing.MockClock.prototype.isTimeoutSet = function(timeoutKey) {
<a name="line274"></a>  return timeoutKey &lt;= this.timeoutsMade_ &amp;&amp; !this.deletedKeys_[timeoutKey];
<a name="line275"></a>};
<a name="line276"></a>
<a name="line277"></a>
<a name="line278"></a>/**
<a name="line279"></a> * Runs any function that is scheduled before a certain time.  Timeouts can
<a name="line280"></a> * be made to fire early or late if timeoutDelay_ is non-0.
<a name="line281"></a> * @param {number} endTime The latest time in the range, in milliseconds.
<a name="line282"></a> * @private
<a name="line283"></a> */
<a name="line284"></a>goog.testing.MockClock.prototype.runFunctionsWithinRange_ = function(
<a name="line285"></a>    endTime) {
<a name="line286"></a>  var adjustedEndTime = endTime - this.timeoutDelay_;
<a name="line287"></a>
<a name="line288"></a>  // Repeatedly pop off the last item since the queue is always sorted.
<a name="line289"></a>  while (this.queue_.length &amp;&amp;
<a name="line290"></a>      this.queue_[this.queue_.length - 1].runAtMillis &lt;= adjustedEndTime) {
<a name="line291"></a>    var timeout = this.queue_.pop();
<a name="line292"></a>
<a name="line293"></a>    if (!(timeout.timeoutKey in this.deletedKeys_)) {
<a name="line294"></a>      // Only move time forwards.
<a name="line295"></a>      this.nowMillis_ = Math.max(this.nowMillis_,
<a name="line296"></a>          timeout.runAtMillis + this.timeoutDelay_);
<a name="line297"></a>      // Call timeout in global scope and pass the timeout key as the argument.
<a name="line298"></a>      timeout.funcToCall.call(goog.global, timeout.timeoutKey);
<a name="line299"></a>      // In case the interval was cleared in the funcToCall
<a name="line300"></a>      if (timeout.recurring) {
<a name="line301"></a>        this.scheduleFunction_(
<a name="line302"></a>            timeout.timeoutKey, timeout.funcToCall, timeout.millis, true);
<a name="line303"></a>      }
<a name="line304"></a>    }
<a name="line305"></a>  }
<a name="line306"></a>};
<a name="line307"></a>
<a name="line308"></a>
<a name="line309"></a>/**
<a name="line310"></a> * Schedules a function to be run at a certain time.
<a name="line311"></a> * @param {number} timeoutKey The timeout key.
<a name="line312"></a> * @param {Function} funcToCall The function to call.
<a name="line313"></a> * @param {number} millis The number of milliseconds to call it in.
<a name="line314"></a> * @param {boolean} recurring Whether to function call should recur.
<a name="line315"></a> * @private
<a name="line316"></a> */
<a name="line317"></a>goog.testing.MockClock.prototype.scheduleFunction_ = function(
<a name="line318"></a>    timeoutKey, funcToCall, millis, recurring) {
<a name="line319"></a>  var timeout = {
<a name="line320"></a>    runAtMillis: this.nowMillis_ + millis,
<a name="line321"></a>    funcToCall: funcToCall,
<a name="line322"></a>    recurring: recurring,
<a name="line323"></a>    timeoutKey: timeoutKey,
<a name="line324"></a>    millis: millis
<a name="line325"></a>  };
<a name="line326"></a>
<a name="line327"></a>  goog.testing.MockClock.insert_(timeout, this.queue_);
<a name="line328"></a>};
<a name="line329"></a>
<a name="line330"></a>
<a name="line331"></a>/**
<a name="line332"></a> * Inserts a timer descriptor into a descending-order queue.
<a name="line333"></a> *
<a name="line334"></a> * Later-inserted duplicates appear at lower indices.  For example, the
<a name="line335"></a> * asterisk in (5,4,*,3,2,1) would be the insertion point for 3.
<a name="line336"></a> *
<a name="line337"></a> * @param {Object} timeout The timeout to insert, with numerical runAtMillis
<a name="line338"></a> *     property.
<a name="line339"></a> * @param {Array.&lt;Object&gt;} queue The queue to insert into, with each element
<a name="line340"></a> *     having a numerical runAtMillis property.
<a name="line341"></a> * @private
<a name="line342"></a> */
<a name="line343"></a>goog.testing.MockClock.insert_ = function(timeout, queue) {
<a name="line344"></a>  // Although insertion of N items is quadratic, requiring goog.structs.Heap
<a name="line345"></a>  // from a unit test will make tests more prone to breakage.  Since unit
<a name="line346"></a>  // tests are normally small, scalability is not a primary issue.
<a name="line347"></a>
<a name="line348"></a>  // Find an insertion point.  Since the queue is in reverse order (so we
<a name="line349"></a>  // can pop rather than unshift), and later timers with the same time stamp
<a name="line350"></a>  // should be executed later, we look for the element strictly greater than
<a name="line351"></a>  // the one we are inserting.
<a name="line352"></a>
<a name="line353"></a>  for (var i = queue.length; i != 0; i--) {
<a name="line354"></a>    if (queue[i - 1].runAtMillis &gt; timeout.runAtMillis) {
<a name="line355"></a>      break;
<a name="line356"></a>    }
<a name="line357"></a>    queue[i] = queue[i - 1];
<a name="line358"></a>  }
<a name="line359"></a>
<a name="line360"></a>  queue[i] = timeout;
<a name="line361"></a>};
<a name="line362"></a>
<a name="line363"></a>
<a name="line364"></a>/**
<a name="line365"></a> * Maximum 32-bit signed integer.
<a name="line366"></a> *
<a name="line367"></a> * Timeouts over this time return immediately in many browsers, due to integer
<a name="line368"></a> * overflow.  Such known browsers include Firefox, Chrome, and Safari, but not
<a name="line369"></a> * IE.
<a name="line370"></a> *
<a name="line371"></a> * @type {number}
<a name="line372"></a> * @private
<a name="line373"></a> */
<a name="line374"></a>goog.testing.MockClock.MAX_INT_ = 2147483647;
<a name="line375"></a>
<a name="line376"></a>
<a name="line377"></a>/**
<a name="line378"></a> * Schedules a function to be called after &#39;millis&#39; milliseconds.
<a name="line379"></a> * Mock implementation for window.setTimeout
<a name="line380"></a> * @param {Function} funcToCall The function to call.
<a name="line381"></a> * @param {number} millis The number of milliseconds to call it after.
<a name="line382"></a> * @return {number} The number of timeouts created.
<a name="line383"></a> * @private
<a name="line384"></a> */
<a name="line385"></a>goog.testing.MockClock.prototype.setTimeout_ = function(funcToCall, millis) {
<a name="line386"></a>  if (millis &gt; goog.testing.MockClock.MAX_INT_) {
<a name="line387"></a>    throw Error(
<a name="line388"></a>        &#39;Bad timeout value: &#39; + millis + &#39;.  Timeouts over MAX_INT &#39; +
<a name="line389"></a>        &#39;(24.8 days) cause timeouts to be fired &#39; +
<a name="line390"></a>        &#39;immediately in most browsers, except for IE.&#39;);
<a name="line391"></a>  }
<a name="line392"></a>  this.timeoutsMade_ = this.timeoutsMade_ + 1;
<a name="line393"></a>  this.scheduleFunction_(this.timeoutsMade_, funcToCall, millis, false);
<a name="line394"></a>  return this.timeoutsMade_;
<a name="line395"></a>};
<a name="line396"></a>
<a name="line397"></a>
<a name="line398"></a>/**
<a name="line399"></a> * Schedules a function to be called every &#39;millis&#39; milliseconds.
<a name="line400"></a> * Mock implementation for window.setInterval
<a name="line401"></a> * @param {Function} funcToCall The function to call.
<a name="line402"></a> * @param {number} millis The number of milliseconds between calls.
<a name="line403"></a> * @return {number} The number of timeouts created.
<a name="line404"></a> * @private
<a name="line405"></a> */
<a name="line406"></a>goog.testing.MockClock.prototype.setInterval_ = function(funcToCall, millis) {
<a name="line407"></a>  this.timeoutsMade_ = this.timeoutsMade_ + 1;
<a name="line408"></a>  this.scheduleFunction_(this.timeoutsMade_, funcToCall, millis, true);
<a name="line409"></a>  return this.timeoutsMade_;
<a name="line410"></a>};
<a name="line411"></a>
<a name="line412"></a>
<a name="line413"></a>/**
<a name="line414"></a> * Clears a timeout.
<a name="line415"></a> * Mock implementation for window.clearTimeout
<a name="line416"></a> * @param {number} timeoutKey The timeout key to clear.
<a name="line417"></a> * @private
<a name="line418"></a> */
<a name="line419"></a>goog.testing.MockClock.prototype.clearTimeout_ = function(timeoutKey) {
<a name="line420"></a>  this.deletedKeys_[timeoutKey] = true;
<a name="line421"></a>};
<a name="line422"></a>
<a name="line423"></a>
<a name="line424"></a>/**
<a name="line425"></a> * Clears an interval.
<a name="line426"></a> * Mock implementation for window.clearInterval
<a name="line427"></a> * @param {number} timeoutKey The interval key to clear.
<a name="line428"></a> * @private
<a name="line429"></a> */
<a name="line430"></a>goog.testing.MockClock.prototype.clearInterval_ = function(timeoutKey) {
<a name="line431"></a>  this.deletedKeys_[timeoutKey] = true;
<a name="line432"></a>};
</pre>


</body>
</html>
